CPager Class

A pager control is a window container that is used with a window that does not have enough display area to show all of its content. The pager control allows the user to scroll to the area of the window that is not currently in view.

See: About Pager Controls

Include file: CPager.inc

Name	Description
ForwardMouse	Enables or disables mouse forwarding for the pager control.
GetBkColor	Retrieves the current background color for the pager control.
GetBorder	Retrieves the current border size for the pager control.
GetButtonSize	Retrieves the current button size for the pager control.
GetButtonState	Retrieves the state of the specified button in a pager control.
GetDropTarget	Retrieves a pager control’s IDropTarget interface pointer.
GetPos	Retrieves the current scroll position of the pager control.
RecalcSize	Forces the pager control to recalculate the size of the contained window.
SetBkColor	Sets the current background color for the pager control.
SetBorder	Sets the current border size for the pager control.
SetButtonSize	Sets the current button size for the pager control.
SetChild	Sets the contained window for the pager control.
SetPos	Sets the scroll position for the pager control.

ForwardMouse

Enables or disables mouse forwarding for the pager control. When mouse forwarding is enabled, the pager control forwards WM_MOUSEMOVE messages to the contained window.

SUB ForwardMouse (BYVAL hPager AS HWND, BYVAL bForward AS BOOLEAN)

Parameter	Description
hPager	Handle to the pager control.
bForward	BOOL value that determines if mouse forwarding is enabled or disabled. If this value is nonzero, mouse forwarding is enabled. If this value is zero, mouse forwarding is disabled.

Usage example

CPager.ForwardMouse(hPager, TRUE)

GetBkColor

Retrieves the current background color for the pager control.

FUNCTION GetBkColor (BYVAL hPager AS HWND) AS COLORREF

Parameter	Description
hPager	Handle to the pager control.
bForward	BOOL value that determines if mouse forwarding is enabled or disabled. If this value is nonzero, mouse forwarding is enabled. If this value is zero, mouse forwarding is disabled.

Return value

Returns the current background color.

Remarks

By default, the pager control will use the system button face color as the background color. This is the same color that can be retrieved by calling GetSysColorBrush with COLOR_BTNFACE.

Usage example

DIM bkColor AS COLORREF = CPager.GetBkColor(hPager)

GetBorder

Retrieves the current border size for the pager control.

FUNCTION GetBorder (BYVAL hPager AS HWND) AS LONG

Parameter	Description
hPager	Handle to the pager control.

Return value

Returns the current border size, in pixels.

Usage example

DIM nSize AS LONG = CPager.GetBorder(hPager)

GetButtonSize

Retrieves the current button size for the pager control.

FUNCTION GetButtonSize (BYVAL hPager AS HWND) AS LONG

Parameter	Description
hPager	Handle to the pager control.

Return value

Returns the current button size, in pixels.

Usage example

DIM nSize AS LONG = CPager.GetButtonSize(hPager)

GetButtonState

Retrieves the state of the specified button in a pager control.

FUNCTION GetButtonState (BYVAL hPager AS HWND, BYVAL iButton AS LONG) AS DWORD

Parameter	Description
hPager	Handle to the pager control.
iButton	Indicates which button to retrieve the state for.

** iButton state values **

Value	Meaning
PGB_TOPORLEFT	Indicates the top button in a PGS_VERT pager control or the left button in a PGS_HORZ pager control.
PGB_BOTTOMORRIGHT	Indicates the bottom button in a PGS_VERT pager control or the right button in a PGS_HORZ pager control.

Return value

Returns the state of the button specified in lParam. This will be one or more of the following values (if more than one value is returned they will be combined using a bitwise OR):

Return code	Description
PGF_INVISIBLE	The button is not visible.
PGF_NORMAL	The button is in normal state.
PGF_NORMAL	The button is in normal state.
PGF_GRAYED	The button is in grayed state.
PGF_DEPRESSED	The button is in pressed state.
PGF_HOT	The button is in hot state.

Usage example

DIM state AS LONG = CPager.GetButtonState(hPager, PGB_TOPORLEFT)

GetDropTarget

Retrieves a pager control’s IDropTarget interface pointer.

FUNCTION GetDropTarget (BYVAL hPager AS HWND, BYVAL ppdt AS IDropTarget PTR PTR)
FUNCTION GetDropTarget (GetDropTarget (BYVAL hPager AS HWND) AS IDropTarget PTR

Parameter	Description
hPager	Handle to the pager control.
ppdt	Pointer to an IDropTarget pointer that receives the interface pointer. It is the caller’s responsibility to call Release on this pointer when it is no longer needed.

Return value

Returns the pager control’s IDropTarget interface pointer.

Usage examples

DIM pdt AS IDropTarget PTR
CPager.GetDropTarget(hPager, @pdt))
pdt = CPager.GetDropTarget(hPager)

GetPos

Retrieves the current scroll position of the pager control.

FUNCTION GetPos (BYVAL hPager AS HWND) AS LONG

Parameter	Description
hPager	Handle to the pager control.

Return value

Returns the current scroll position, in pixels.

Usage example

DIM pos AS LOG = CPager.GetPos(hPager)

RecalcSize

Forces the pager control to recalculate the size of the contained window. Using this macro will result in a PGN_CALCSIZE notification being sent.

SUB RecalcSize (BYVAL hPager AS HWND)

Parameter	Description
hPager	Handle to the pager control.

Usage example

CPager.RecalcSize(hPager)

SetBkColor

Sets the current background color for the pager control.

FUNCTION SetBkColor (BYVAL hPager AS HWND, BYVAL clr AS COLORREF) AS COLORREF

Parameter	Description
hPager	Handle to the pager control.
clr	COLORREF value that contains the new background color of the pager control.

Return value

Returns a COLORREF value that contains the previous background color.

Usage example

CPager.SetBkColor(hPager, RGB_BLUE)

Remarks

By default, the pager control will use the system button face color as the background color. This is the same color that can be retrieved by calling GetSysColorBrush with COLOR_BTNFACE.

SetBorder

Sets the current border size for the pager control.

FUNCTION SetBorder (BYVAL hPager AS HWND, BYVAL iBorder AS LONG) AS LONG

Parameter	Description
hPager	Handle to the pager control.
iBorder	New size of the border, in pixels. This value should not be larger than the pager button or less than zero. If iBorder is too large, the border will be drawn the same size as the button. If iBorder is negative, the border size will be set to zero.

Return value

Returns the previous border size, in pixels.

Usage example

CPager.SetBorder(hPager, 2)

SetButtonSize

Sets the current button size for the pager control.

FUNCTION SetButtonSize (BYVAL hPager AS HWND, BYVAL iSize AS LONG) AS LONG

Parameter	Description
hPager	Handle to the pager control.
iSize	The new button size, in pixels.

Return value

Returns the previous button size, in pixels.

Usage example

DIM nSize AS LONG = CPager.SetButtonSize(hPager, 25)

Remarks

If the pager control has the PGS_HORZ style, the button size determines the width of the pager buttons. If the pager control has the PGS_VERT style, the button size determines the height of the pager buttons. By default, the pager control sets its button size to three-fourths of the width of the scroll bar.

SetChild

Sets the contained window for the pager control. This macro will not change the parent of the contained window; it only assigns a window handle to the pager control for scrolling. In most cases, the contained window will be a child window. If this is the case, the contained window should be a child of the pager control.

SUB SetChild (BYVAL hPager AS HWND, BYVAL hwndChild AS HWND)

Parameter	Description
hPager	Handle to the pager control.
hwndChild	Handle to the window to be contained.

Return value

Returns the previous button size, in pixels.

Usage example

DIM nSize AS LONG = CPager.SetButtonSize(hPager, 25)

SetPos

Sets the scroll position for the pager control.

FUNCTION SetPos (BYVAL hPager AS HWND, BYVAL iPos AS LONG) AS LONG

Parameter	Description
hPager	Handle to the pager control.
iPos	The new scroll position, in pixels.

Usage example

CPager.SetPos(hPager, 20)